Skip to content

docs: document Zero --security token and whitelist flags - #762

Merged
matthewmcneely merged 2 commits into
mainfrom
docs-zero-security-flags
Aug 17, 2026
Merged

docs: document Zero --security token and whitelist flags#762
matthewmcneely merged 2 commits into
mainfrom
docs-zero-security-flags

Conversation

@matthewmcneely

@matthewmcneely matthewmcneely commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Documents the --security superflag on dgraph zero, which authenticates Zero's administrative HTTP endpoints (/state, /assign, /removeNode, /moveTablet) using the same token and whitelist options Alpha already supports.

What changed

  • cli/zero.md — adds --security to the superflag list, a new "Securing the admin HTTP endpoints" section with usage examples, and the flag block in the Full Reference.
  • cli/superflags.md — the Security superflag token and whitelist options now list zero under "Applies to", with a pointer to the admin-endpoint-security page.
  • admin/security/admin-endpoint-security.md — a new "Zero admin endpoints" section describing how the flag protects these endpoints.

Behavior documented

  • The destructive endpoints (/removeNode, /moveTablet) are restricted to loopback by default. A whitelist or token is required to reach them from another host.
  • The informational and allocation endpoints (/state, /assign) are enforced once a token or whitelist is configured.
  • Network isolation of the port (it is an internal control-plane port) remains the primary control, and --limit "disable-admin-http=true" turns the endpoints off entirely.

Notes

  • --security on Zero shipped in v25.4.0 (2026-07-30), so this targets docs/ (next) only. An earlier revision also patched docs_versioned_docs/version-v25.3/; those files are reverted in 1b33ca1, since the flag is in no v25.3.x binary.
  • Lands just ahead of the v25.4 version cut, which snapshots docs/ into docs_versioned_docs/version-v25.4/ and promotes v25.4 to the version served as latest.

Zero now supports the --security superflag (token, whitelist) to
authenticate its administrative HTTP endpoints (/state, /assign,
/removeNode, /moveTablet). Document the flag on the dgraph zero CLI page,
add zero to the Security superflag table, and add a "Zero admin
endpoints" section to Admin Endpoint Security describing the two-tier
protection: /removeNode and /moveTablet are loopback-only by default,
while /state and /assign are enforced once a token or whitelist is set.

Applied to both docs/ (next) and the served v25.3 version.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@matthewmcneely
matthewmcneely requested a review from rderbier as a code owner July 17, 2026 19:42
@matthewmcneely

matthewmcneely commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator Author

Merge only when v25.4.0 is released.

@matthewmcneely

Copy link
Copy Markdown
Collaborator Author

@raphael-istari Can you pull the levers here. Just released v25.4.0 (https://github.com/orgs/dgraph-io/discussions/9804)

The --security superflag on Zero ships in v25.4.0, so documenting it in
the v25.3 snapshot would describe a flag absent from every v25.3.x
binary. Revert the three version-v25.3 files and keep the change in
docs/, where the v25.4 cut will pick it up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@matthewmcneely
matthewmcneely merged commit 12d0f53 into main Aug 17, 2026
1 check passed
@matthewmcneely
matthewmcneely deleted the docs-zero-security-flags branch August 17, 2026 20:29
matthewmcneely added a commit that referenced this pull request Aug 17, 2026
Cuts the v25.4 documentation version and promotes it to the version
served at the site root, matching the
[v25.4.0](https://github.com/dgraph-io/dgraph/releases/tag/v25.4.0)
release (2026-07-30).

## Summary

- Snapshots `docs/` into `docs_versioned_docs/version-v25.4/` and
`docs-graphql/` into `graphql_versioned_docs/version-v25.4/`, via
`docs:version:docs` and `docs:version:graphql`.
- Sets `lastVersion: 'v25.4'` on both content plugins, with v25.4 at
path `''` and v25.3 moved to `v25.3`.
- The snapshot carries the Zero `--security` documentation merged in
#762, the one user-facing change in v25.4.0.

## Also in here: a graphql version-map repair

Worth a look, since it is easy to miss in a 227-file diff. The v25.3 cut
(b75fd1a) added `"v25.3"` to `graphql_versions.json` but never added a
matching entry to the graphql plugin's `versions` map in
`docusaurus.config.ts`. Docusaurus fell back to defaults for it, so
`/graphql/` kept serving **v25.2 (latest)** while v25.3 sat above it in
the dropdown as an older version. Both v25.3 and v25.4 now have explicit
entries, and the GraphQL section moves from v25.2 to v25.4 as latest.

## URL movement

Normal for any cut, but the GraphQL section advances two versions at
once:

| Path | Before | After |
|------|--------|-------|
| `/<page>` | v25.3 | v25.4 |
| `/v25.3/<page>` | 404 | v25.3 |
| `/graphql/<page>` | v25.2 | v25.4 |
| `/graphql/v25.2/<page>` | 404 | v25.2 |
| `/graphql/v25.3/<page>` | v25.3 | v25.3 (unchanged) |

## Testing

`npm run build` passes. With `onBrokenLinks: 'throw'`, a clean build is
the link check across all five versions. Verified against the generated
output in `build/`:

- `/` and `/graphql/` both render **v25.4 (latest)**, with v25.3, v25.2,
v25.1, and v24.1 in the dropdown.
- `/cli/zero` and `/admin/security/admin-endpoint-security` include the
`--security` content; `/v25.3/` equivalents do not, since the flag is in
no v25.3.x binary.
- All eight older-version paths resolve.

<!-- codesmith:footer -->
---
<a
href="https://app.blacksmith.sh/dgraph-io/codesmith/dgraph-docs/pr/763"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-light-v2.svg"><img
alt="View with [code]smith"
src="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg"></picture></a>
<a
href="https://backend.blacksmith.sh/track/enable-autofix?expires=1789590779&installation_model_id=8575&pr_number=763&repository=dgraph-io%2Fdgraph-docs&return_to=https%3A%2F%2Fgithub.com%2Fdgraph-io%2Fdgraph-docs%2Fpull%2F763&signature=3bf007c45407e0b8760de847127da3361c5f701c21fb69d538e230f18b11e58f"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-light.svg"><img
alt="Autofix with [code]smith"
src="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"></picture></a>
<sup>Need help on this PR? Tag <code>@codesmith-bot</code> with what you
need. Autofix is disabled.</sup>

<!-- codesmith:autofix:disabled -->
<!-- /codesmith:footer -->

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant